![Chat](https://img.shields.io/badge/chat-discussions-success.svg)
Command line interface to inspect and change markdown files with remark.
Contents
What is this?
This package is a command line interface (CLI) that you can use in your terminal
or in npm scripts and the like to inspect and change markdown files.
This CLI is built around remark, which is a very popular ecosystem of plugins
that work with markdown as structured data, specifically ASTs (abstract syntax
trees).
You can choose from the 150+ plugins that already exist or make your own.
See the monorepo readme for info on what the remark ecosystem is.
When should I use this?
You can use this package when you want to work with the markdown files in your
project from the command line.
remark-cli
has many options and you can combine it with many plugins, so it
should be possible to do what you want.
If not, you can always use remark
itself manually in a script.
Install
This package is ESM only.
In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:
npm install remark-cli
Use
Add a table of contents with remark-toc
to readme.md
:
remark readme.md --use remark-toc --output
Lint all markdown files in the current directory according to the markdown style
guide with remark-preset-lint-markdown-style-guide
.
remark . --use remark-preset-lint-markdown-style-guide
CLI
The interface of remark-cli
is explained as follows on its help page
(remark --help
):
Usage: remark [options] [path | glob ...]
CLI to process markdown with remark
Options:
-h --help output usage information
-v --version output version number
-o --output [path] specify output location
-r --rc-path <path> specify configuration file
-i --ignore-path <path> specify ignore file
-s --setting <settings> specify settings
-e --ext <extensions> specify extensions
-u --use <plugins> use plugins
-w --watch watch for changes and reprocess
-q --quiet output only warnings and errors
-S --silent output only errors
-f --frail exit with 1 on warnings
-t --tree specify input and output as syntax tree
--report <reporter> specify reporter
--file-path <path> specify path to process as
--ignore-path-resolve-from dir|cwd resolve patterns in `ignore-path` from its directory or cwd
--ignore-pattern <globs> specify ignore patterns
--silently-ignore do not fail when given ignored files
--tree-in specify input as syntax tree
--tree-out output syntax tree
--inspect output formatted syntax tree
--[no-]stdout specify writing to stdout (on by default)
--[no-]color specify color in report (on by default)
--[no-]config search for configuration files (on by default)
--[no-]ignore search for ignore files (on by default)
Examples:
# Process `input.md`
$ remark input.md -o output.md
# Pipe
$ remark < input.md > output.md
# Rewrite all applicable files
$ remark . -o
More information on all these options is available at
unified-args
, which does the work.
remark-cli
is unified-args
preconfigured to:
Examples
Example: checking and formatting markdown on the CLI
This example checks and formats markdown with remark-cli
.
It assumes you’re in a Node.js package.
First, install the CLI and plugins:
npm install remark-cli remark-toc remark-preset-lint-consistent remark-preset-lint-recommended --save-dev
Now, add an npm script in your package.json
:
"scripts": {
"format": "remark . --output",
},
💡 Tip: add ESLint and such in the format
script too.
Observe that the above change adds a format
script, which can be run with
npm run format
.
It runs remark on all markdown files (.
) and rewrites them (--output
).
Run ./node_modules/.bin/remark --help
for more info on the CLI.
Then, add a remarkConfig
to your package.json
to configure remark:
"remarkConfig": {
"settings": {
"bullet": "*",
},
"plugins": [
"remark-preset-lint-consistent",
"remark-preset-lint-recommended",
[
"remark-toc",
{
"heading": "contents"
}
]
]
},
👉 Note: you must remove the comments in the above examples when
copy/pasting them, as comments are not supported in package.json
files.
Finally, you can run the npm script to check and format markdown files in your
project:
npm run format
Example: config files (JSON, YAML, JS)
In the previous example, we saw that remark-cli
was configured from within a
package.json
file.
That’s a good place when the configuration is relatively short, when you have a
package.json
, and when you don’t need comments (which are not allowed in
JSON).
You can also define configuration in separate files in different languages.
With the package.json
config as inspiration, here’s a JavaScript version that
can be placed in .remarkrc.js
:
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkToc from 'remark-toc'
const remarkConfig = {
settings: {
bullet: '*',
},
plugins: [
remarkPresetLintConsistent,
remarkPresetLintRecommended,
[remarkToc, {heading: 'contents'}]
]
}
export default remarkConfig
This is the same configuration in YAML, which can be placed in .remarkrc.yml
:
settings:
bullet: "*"
plugins:
- remark-preset-lint-consistent
- remark-preset-lint-recommended
- - remark-toc
- heading: contents
When remark-cli
is about to process a markdown file it’ll search the file
system upwards for configuration files starting at the folder where that file
exists.
Take the following file structure as an illustration:
folder/
├─ subfolder/
│ ├─ .remarkrc.json
│ └─ file.md
├─ .remarkrc.js
├─ package.json
└─ readme.md
When folder/subfolder/file.md
is processed, the closest config file is
folder/subfolder/.remarkrc.json
.
For folder/readme.md
, it’s folder/.remarkrc.js
.
The order of precedence is as follows.
Earlier wins (so in the above file structure folder/.remarkrc.js
wins over
folder/package.json
):
.remarkc
(JSON).remarkc.json
(JSON).remarkc.cjs
(CJS).remarkc.mjs
(ESM).remarkc.js
(CJS or ESM, depending on type: 'module'
in package.json
).remarkc.yaml
(YAML).remarkc.yml
(YAML)package.json
with remarkConfig
field
Compatibility
Projects maintained by the unified collective are compatible with all maintained
versions of Node.js.
As of now, that is Node.js 12.20+, 14.14+, and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.
Security
As markdown can be turned into HTML and improper use of HTML can open you up to
cross-site scripting (XSS) attacks, use of remark can be unsafe.
When going to HTML, you will likely combine remark with rehype, in which
case you should use rehype-sanitize
.
Use of remark plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.
For info on how to submit a report, see our security policy.
Contribute
See contributing.md
in remarkjs/.github
for ways
to get started.
See support.md
for ways to get help.
Join us in Discussions to chat with the community and contributors.
This project has a code of conduct.
By interacting with this repository, organization, or community you agree to
abide by its terms.
Support this effort and give back by sponsoring on OpenCollective!
License
MIT © Titus Wormer