Provide a CLI based on `unified-args`

remcohaszing commented 1 year ago

Initial checklist

[X] I read the support docs
[X] I read the contributing guide
[X] I agree to follow the code of conduct
[X] I searched issues and couldn’t find anything (or linked relevant results below)

Problem

The unified ecosystem has some CLIs based on unified-args that can be used for linting and formatting. Since MDX is based on remark, remark-cli can support MDX, but it’s not obvious. By default remark-cli doesn’t contain remark-mdx, not does it check .mdx files by default.

It would be nice if there is a simple blessed way to lint MDX files.

Solution

Create a new package remark-mdx-cli. This registers the remark-mdx command.

#!/usr/bin/env node

/**
 * @typedef Pack
 * @property {string} name
 * @property {string} version
 * @property {string} description
 */

import fs from 'node:fs/promises'
import {remark} from 'remark'
import remarkMdx from 'remark-mdx'
import {args} from 'unified-args'

/** @type {Pack} */
const cli = JSON.parse(
  String(await fs.readFile(new URL('package.json', import.meta.url)))
)

args({
  description: cli.description,
  extensions: ['mdx'],
  ignoreName: '.remarkmdxignore',
  name: 'remark-mdx',
  packageField: 'remarkmdxConfig',
  pluginPrefix: 'remark',
  processor: remark.use(remarkMdx),
  rcName: '.remarkmdxrc',
  version: cli.name + ': ' + cli.version
})

This will also be accompanied by a language server (remark-mdx-language-server) and VSCode plugin (unifiedjs.vscode-remark-mdx) based on unified-language-server.

Alternatives

There are plenty of variations possible on the names of various parameters. I.e. should the package name be scoped? Should the command be different? Should it use .remarkignore instead of .remarkmdxignore?

wooorm commented 1 year ago

simple way is remark -e mdx -u mdx? Not sure if another CLI that needs to be documented is an improvement, over adding docs somewhere on how to do this?

wooorm commented 1 year ago

By extension, should we have remark-gfm-cli? What if you want to combine both?

wooorm commented 1 year ago

And, wouldn’t an MDX CLI be more about compiling/evaluating code?

remcohaszing commented 1 year ago

IMO configuration is usually preferred over CLI arguments.

Configuration gives the user a standard place to define it.
Configuration can be shared between integrations.

This goes for other tooling as well. I.e. it’s perfectly possible to run git, Prettier, or ESLint using CLI arguments and no configuration, but it’s very inconvenient and you don’t get editor integrations. IMO this falls in the same category.

Perhaps we could also investigate an MDX CLI for compiling code, but that’s a different issue and I don’t see a need for that right now.

remcohaszing commented 1 year ago

The difference between GFM and MDX is that typically it’s fine to treat other .md files as GFM, but it’s not ok to treat .md files as MDX, or .mdx files as regular markdown.

wooorm commented 1 year ago

you can already use remark-mdx in configuration
markdown and MDX are, except for .mdx and remark-mdx, very similar. This project uses shared configuration for both. Duplicating all of the config files seems superfluous. Like having an eslintjsxrc, eslintjsrc, eslinttsrc.
integrations including .mdx, and then applying remark-mdx, but otherwise loading all the remark ignore files / config files seems better to me

wooorm commented 1 month ago

Closing this as an issue: we can use discussions for discussions. Then we can use issues for actionable things. It remains vague to me what this is about. There could be many CLIs for MDX. If this is about linting, perhaps there could be a new guide, discussing how to lint and format MDX? One such is a type checking CLI, which is discussed: https://github.com/mdx-js/mdx-analyzer/issues/292.

mdx-js / mdx