Provide a CLI based on `unified-args`
remcohaszing opened this issue · comments
Initial checklist
- I read the support docs
- I read the contributing guide
- I agree to follow the code of conduct
- 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
?
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?
By extension, should we have remark-gfm-cli
? What if you want to combine both?
And, wouldn’t an MDX CLI be more about compiling/evaluating code?
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.
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.
- you can already use
remark-mdx
in configuration - markdown and MDX are, except for
.mdx
andremark-mdx
, very similar. This project uses shared configuration for both. Duplicating all of the config files seems superfluous. Like having aneslintjsxrc
,eslintjsrc
,eslinttsrc
. - integrations including
.mdx
, and then applyingremark-mdx
, but otherwise loading all the remark ignore files / config files seems better to me