I am unable to disable a custom rule

[wdcryer]

Hello,

TLDR: I can't figure out how to disable a custom Remark Lint rule in MDX 3 files. I tried {/* lint disable no-markdown-in-jsx */} and it doesn't seem to work.

I am writing a custom Remark Lint rule that's fairly simple. We have a large Docusaurus site that currently uses MDX 1. We are upgrading to MDX 3, which parses string children of elements in MDX files as markdown if they are on a new line.

<SomeComponent>
  I will be turned into an HTML paragraph element.
</SomeComponent>

We do not want children of elements or components to be parsed as Markdown in 99% of cases, so the lint rule wraps JSX elements in curly braces to prevent their children from being parsed as markdown.

{
<SomeComponent>
  I will NOT be turned into an HTML paragraph element.
</SomeComponent>
}

However, there are a few cases where we want the children to be parsed as markdown, so we need to be able to disable the rule. I tried using JS comments to disable it, but it doesn't work. The element still gets wrapped in curly braces.

{/* lint disable no-markdown-in-jsx */}
<SomeComponent>
  SomeComponent will get wrapped in curly braces despite the ignore comment above.
</SomeComponent>
{/* lint enable no-markdown-in-jsx */}

I export it like so:

const noMarkdownInJsx = lintRule('remark-lint:no-markdown-in-jsx', rule);

export default noMarkdownInJsx;

Then I import it in my .remarkrc.mjs file.

import noMarkdownInJsx from './remark-lint-rules/noMarkdownInJsx.mjs';

const remarkConfig = {
  settings: {
    // settings omitted
  },
  plugins: [
    // other rules omitted
    noMarkdownInJsx,
  ],
};

export default remarkConfig;

Perhaps the issue is that my rule is modifying the markdown AST no matter what (parent.children.splice(index, 1, newNode)). Is there an easy way to plug into the rule disabling mechanism?

edit for more info:
My original lint rule was written as follows:

import { unified } from 'unified';
import { lintRule } from 'unified-lint-rule';
import markdown from 'remark-parse';
import mdx from 'remark-mdx';
import frontmatter from 'remark-frontmatter';
import stringify from 'remark-stringify';
import { u } from 'unist-builder';
import { visit, SKIP } from 'unist-util-visit';

export const processor = unified()
  .use(frontmatter, ['yaml'])
  .use(markdown)
  .use(mdx)
  .use(stringify, { rule: '-', ruleRepetition: 3 });

/**
 * @typedef {import('unified-lint-rule').Rule} Rule
 * @type Rule
 */
export const rule = (tree, file) => {
  const JSX_ELEMENT = 'mdxJsxFlowElement';

  visit(tree, JSX_ELEMENT, (node, index, parent) => {
    const isParentTheRoot = parent === tree;
    const hasChildren = node.children.length > 0;

    // we only need to wrap JSX elements at the top level of the document
    if (isParentTheRoot && hasChildren) {
      file.message(
        'JSX elements should be wrapped in curly braces, unless you want to allow their descendants to be processed as markdown.',
        node
      );

      const nodeValueAsString = processor.stringify(node);

      const nodeWrappedInCurlyBraces = u(
        'mdxFlowExpression',
        '\n' + nodeValueAsString
      );

      parent.children.splice(index, 1, nodeWrappedInCurlyBraces);

      return [SKIP, index];
    }
  });
};

const noMarkdownInJsx = lintRule('remark-lint:no-markdown-in-jsx', rule);

export default noMarkdownInJsx;

I've since updated it to manually check for comments that disable and enable the rule:

import { unified } from 'unified';
import { lintRule } from 'unified-lint-rule';
import markdown from 'remark-parse';
import mdx from 'remark-mdx';
import frontmatter from 'remark-frontmatter';
import stringify from 'remark-stringify';
import { u } from 'unist-builder';
import { visit, SKIP } from 'unist-util-visit';

const processor = unified()
  .use(frontmatter, ['yaml'])
  .use(markdown)
  .use(mdx)
  .use(stringify, { rule: '-', ruleRepetition: 3 });

/**
 * Text children of JSX elements are parsed as markdown by default.
 * In most cases, we do not want this. For example, it may insert paragraphs
 * inside of our components. This rule wraps JSX elements in curly braces
 * to prevent this behavior.
 *
 * To disable this rule for a specific JSX element, you can add a JS comment with
 * the text "lint disable no-markdown-in-jsx" before the element.
 *
 * Use a JS comment containing "lint enable no-markdown-in-jsx" to re-enable the rule.
 */
const noMarkdownInJsx = lintRule('dp-docs:no-markdown-in-jsx', (tree) => {
  const JSX_ELEMENT = 'mdxJsxFlowElement';
  const FLOW_EXPRESSION = 'mdxFlowExpression';

  let isRuleEnabled = true;

  visit(tree, (node, index, parent) => {
    if (node.type === FLOW_EXPRESSION) {
      const isComment =
        node.value.startsWith('/*') && node.value.endsWith('*/');

      if (isComment) {
        const isLintDisableComment = node.value.includes('lint disable');
        const isLintEnableComment = node.value.includes('lint enable');
        const isTargetingThisRule = node.value.includes('no-markdown-in-jsx');

        if (isTargetingThisRule) {
          if (isLintDisableComment) {
            isRuleEnabled = false;
          }

          if (isLintEnableComment) {
            isRuleEnabled = true;
          }
        }
      }
    } else if (isRuleEnabled && node.type === JSX_ELEMENT) {
      const isParentTheRoot = parent === tree;
      const hasChildren = node.children.length > 0;

      // we only need to wrap JSX elements at the top level of the document
      if (isParentTheRoot && hasChildren) {
        const nodeValueAsString = processor.stringify(node);
        const nodeWrappedInCurlyBraces = u(
          FLOW_EXPRESSION,
          '\n' + nodeValueAsString
        );

        // replace the JSX element with a JSX element wrapped in curly braces
        parent.children.splice(index, 1, nodeWrappedInCurlyBraces);

        // this node has been processed, don't visit it again
        return [SKIP, index];
      }
    }
  });
});

export default noMarkdownInJsx;

My remark configuration is as follows:

import remarkFrontmatter from 'remark-frontmatter';
import remarkLintFileExtension from 'remark-lint-file-extension';
import remarkLintMaximumLineLength from 'remark-lint-maximum-line-length';
import remarkMdx from 'remark-mdx';
import remarkPresetLintConsistent from 'remark-preset-lint-consistent';
import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide';
import remarkPresetLintRecommended from 'remark-preset-lint-recommended';
import noMarkdownInJsx from './remark-lint-rules/noMarkdownInJsx.mjs';

/**
 * @typedef {import('unified').Preset} Preset
 * @type Preset
 */
const remarkConfig = {
  settings: {
    bullet: '-',
    emphasis: '_',
    extensions: ['md', 'mdx'],
    rule: '-', // Use for horizontal rules
    ruleRepetition: 3,
    // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
  },
  plugins: [
    remarkPresetLintMarkdownStyleGuide,
    remarkPresetLintConsistent,
    remarkPresetLintRecommended,
    [remarkMdx, { printWidth: 80 }],
    [remarkLintFileExtension, ['md', 'mdx']],
    [remarkLintMaximumLineLength, false],
    remarkFrontmatter,
    noMarkdownInJsx,
  ],
};

export default remarkConfig;

[ChristianMurphy]

Welcome @wdcryer! 👋

Are you trying to use the plugin through ESLint MDX?
If so have you seen the discussion on mdx-js/eslint-mdx#205 ? (Cc @JounQin)

Or if not, can you share a more complete example or how you have tried configuring remark/mdx?

[wdcryer]

Thanks @ChristianMurphy! I added the script and the configuration in the description.

I hadn't come across that discussion. I am using remark-cli rather than ESLint MDX. Could that be why it's not working? I have also now added a blank line between the comment and the JSX, but that hasn't resolved it. For now my script is manually checking for these comments. Perhaps I wrote it in a way that is not really aware of Remark Lint. I'm just taking the tree and looking for JSX elements, so I don't see how it would be aware of disabled areas of the AST.

[wooorm]

I think this depends on how you wrote your code — the code that you didn’t share, namely noMarkdownInJsx.mjs.

It might be that, because you wrote it a certain way, it expects:

<SomeComponent>
  {/* lint disable no-markdown-in-jsx */}

  SomeComponent will get wrapped in curly braces despite the ignore comment above.
</SomeComponent>

---

You might not need this custom rule though. You could also explain to authors how to escape things in markdown.

Or, that they can wrap things?

<SomeComponent>I will NOT be turned into an HTML
paragraph element.</SomeComponent>

[wdcryer]

Thank you for the quick response! I have added the code to my description. I made this custom rule because we have a lot content that needs to be updated so it does not have p elements within, which messes up the styling. I would have wanted to automate this migration even if we didn't have a rule for code we add in the future. That said, I think we will want to have some automated guards against this behavior, because it's rarely our intent, and we have many outside contributors. I do appreciate the reasoning for making this the default behavior.

I prefer the curly braces to the wrapping just for the sake of keeping line length to a minimum.

[wooorm]

• The MDX you write should be:

  {/* lint ignore no-markdown-in-jsx */}
  
  <SomeComponent>
    Stuff.
  </SomeComponent>

  ignore is the word you look for. As they are blocks, a blank line is good to have.
• lint rules only check; they don‘t mutate the AST; so your AST transforms shouldn’t go here
• apparently, you are saving those generated, mutated, files somewhere? The comment only controls whether you will see a message printed to your terminal in the end, not whether your transform runs (it has already completed)
• the lint verb ruleId comments only work when you use remark-lint as a source; you use dp-docs as a source; with remark-lint:no-markdown-in-jsx in probably works

[wdcryer]

Thank you for all the advice!

• I am using remark . --output --ext md --ext mdx to transform and save the files in place.
• Thanks for the clarification that lint ignore only affects terminal output.
• So I guess this should just be an AST transform rather than a lint rule, but I do want to be able to ignore it when desired, like with ESLint. The Remark Lint comments seemed like a good convention to follow. Is ignoring parts of the AST that have those comments something that I can hook into, or is that something I should add manually into my script?

edit: It looks like digging into remark-message-control, unified-message-control, mdast-comment-marker, and mdast-zone may be worthwhile.

[wooorm]

Most of those packages are all about messages; they work based on their positional info. And then remove messages.

The comments are in the AST. So you can use mdast-comment-marker to parse their syntax. And then choose to do things in your transform.

Though, why use comments? You can look for an attribute on JSX: <SomeComponent someProp />.

But, personally, I wouldn’t do it: MDX already has ways to differentiate between different things:

{
  <SomeComponent>
    This is just JSX, not *emphasis*, no `p`.
  </SomeComponent>
}

<SomeComponent>
  This is MDX, there is a `p` in the thing, and *emphasis* works.
</SomeComponent>

This is <SomeComponent>MDX,
where an *emphasis* works,
and</SomeComponent> there’s a `p` around the thing.

You’re making things that aren’t understood by other MDX tools, think the syntax highlighter here on GH, or the editor tools in VS Code.

[wdcryer]

Got it, thank you so much for all the help!

[remcohaszing]

I see you’re using remark-mdx inside your remark config. That means your MDX files, but also your markdown files are parsed as MDX.

Currently you need to run remark twice, once for markdown, once for MDX.

remark . --output
remark . --output --ext mdx --use remark-mdx

[wdcryer]

Ah, good call. Thanks, I will try that!