Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
remark-cli
Advanced tools
remark-cli - npm Package Compare versions
Comparing version 10.0.0 to 10.0.1
@@ -24,3 +24,2 @@ #!/usr/bin/env node | ||
| args({ | ||
| // @ts-expect-error: fine. | ||
| processor: remark, | ||
@@ -34,3 +33,2 @@ name: proc.name, | ||
| pluginPrefix: proc.name, | ||
| presetPrefix: proc.name + '-preset', | ||
| packageField: proc.name + 'Config', | ||
@@ -37,0 +35,0 @@ rcName: '.' + proc.name + 'rc', |
| { | ||
| "name": "remark-cli", | ||
| "version": "10.0.0", | ||
| "description": "CLI to process markdown with remark", | ||
| "version": "10.0.1", | ||
| "description": "Command line interface to inspect and change markdown files with remark", | ||
| "license": "MIT", | ||
@@ -6,0 +6,0 @@ "keywords": [ |
318
readme.md
@@ -10,15 +10,43 @@ # remark-cli | ||
| Command line interface for [**remark**][remark]. | ||
| Command line interface to inspect and change markdown files with **[remark][]**. | ||
| * Interface by [`unified-args`][unified-args] | ||
| * Loads [`remark-` plugins][plugins] | ||
| * Searches for [markdown extensions][markdown-extensions] | ||
| * Ignores paths found in [`.remarkignore` files][ignore-file] | ||
| * Loads configuration from [`.remarkrc`, `.remarkrc.js` files][config-file] | ||
| * Uses configuration from [`remarkConfig` fields in `package.json` | ||
| files][config-file] | ||
| ## Contents | ||
| * [What is this?](#what-is-this) | ||
| * [When should I use this?](#when-should-i-use-this) | ||
| * [Install](#install) | ||
| * [Use](#use) | ||
| * [CLI](#cli) | ||
| * [Examples](#examples) | ||
| * [Example: checking and formatting markdown on the CLI](#example-checking-and-formatting-markdown-on-the-cli) | ||
| * [Example: config files (JSON, YAML, JS)](#example-config-files-json-yaml-js) | ||
| * [Compatibility](#compatibility) | ||
| * [Security](#security) | ||
| * [Contribute](#contribute) | ||
| * [Sponsor](#sponsor) | ||
| * [License](#license) | ||
| ## 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][remark] 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`][remark-core] itself manually in a script. | ||
| ## Install | ||
| [npm][]: | ||
| This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). | ||
| In Node.js (version 12.20+, 14.14+, or 16.0+), install with [npm][]: | ||
@@ -31,9 +59,13 @@ ```sh | ||
| Add a table of contents with [`remark-toc`][remark-toc] to `readme.md`: | ||
| ```sh | ||
| # Add a table of contents to `readme.md` | ||
| $ remark readme.md --use toc --output | ||
| remark readme.md --use remark-toc --output | ||
| ``` | ||
| # Lint markdown files in the current directory | ||
| # according to the markdown style guide. | ||
| $ remark . --use preset-lint-markdown-style-guide | ||
| Lint all markdown files in the current directory according to the markdown style | ||
| guide with [`remark-preset-lint-markdown-style-guide`][markdown-style-guide]. | ||
| ```sh | ||
| remark . --use remark-preset-lint-markdown-style-guide | ||
| ``` | ||
@@ -43,4 +75,4 @@ | ||
| See [`unified-args`][unified-args], which provides the interface, for more | ||
| info on all available options. | ||
| The interface of `remark-cli` is explained as follows on its help page | ||
| (`remark --help`): | ||
@@ -92,8 +124,174 @@ ```txt | ||
| More information on all these options is available at | ||
| [`unified-args`][unified-args], which does the work. | ||
| `remark-cli` is `unified-args` preconfigured to: | ||
| * Load `remark-` plugins | ||
| * Search for markdown extensions | ||
| ([`.md`, `.markdown`, etc][markdown-extensions]) | ||
| * Ignore paths found in [`.remarkignore` files][ignore-file] | ||
| * Load configuration from | ||
| [`.remarkrc`, `.remarkrc.js`, etc files][config-file] | ||
| * Use configuration from | ||
| [`remarkConfig` fields in `package.json` files][config-file] | ||
| ## 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: | ||
| ```sh | ||
| 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`: | ||
| ```js | ||
| /* … */ | ||
| "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: | ||
| ```js | ||
| /* … */ | ||
| "remarkConfig": { | ||
| "settings": { | ||
| "bullet": "*", // Use `*` for list item bullets (default) | ||
| // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options. | ||
| }, | ||
| "plugins": [ | ||
| "remark-preset-lint-consistent", // Check that markdown is consistent. | ||
| "remark-preset-lint-recommended", // Few recommended rules. | ||
| [ | ||
| // Generate a table of contents in `## Contents` | ||
| "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: | ||
| ```sh | ||
| 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`: | ||
| ```js | ||
| import remarkPresetLintConsistent from 'remark-preset-lint-consistent' | ||
| import remarkPresetLintRecommended from 'remark-preset-lint-recommended' | ||
| import remarkToc from 'remark-toc' | ||
| const remarkConfig = { | ||
| settings: { | ||
| bullet: '*', // Use `*` for list item bullets (default) | ||
| // See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options. | ||
| }, | ||
| plugins: [ | ||
| remarkPresetLintConsistent, // Check that markdown is consistent. | ||
| remarkPresetLintRecommended, // Few recommended rules. | ||
| // Generate a table of contents in `## Contents` | ||
| [remarkToc, {heading: 'contents'}] | ||
| ] | ||
| } | ||
| export default remarkConfig | ||
| ``` | ||
| This is the same configuration in YAML, which can be placed in `.remarkrc.yml`: | ||
| ```yml | ||
| settings: | ||
| bullet: "*" | ||
| plugins: | ||
| # Check that markdown is consistent. | ||
| - remark-preset-lint-consistent | ||
| # Few recommended rules. | ||
| - remark-preset-lint-recommended | ||
| # Generate a table of contents in `## Contents` | ||
| - - 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: | ||
| ```txt | ||
| 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`): | ||
| 1. `.remarkc` (JSON) | ||
| 2. `.remarkc.json` (JSON) | ||
| 3. `.remarkc.cjs` (CJS) | ||
| 4. `.remarkc.mjs` (ESM) | ||
| 5. `.remarkc.js` (CJS or ESM, depending on `type: 'module'` in `package.json`) | ||
| 6. `.remarkc.yaml` (YAML) | ||
| 7. `.remarkc.yml` (YAML) | ||
| 8. `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 is sometimes used for HTML, and improper use of HTML can open you up | ||
| to a [cross-site scripting (XSS)][xss] attack, use of remark can also be unsafe. | ||
| When going to HTML, use remark in combination with the [**rehype**][rehype] | ||
| ecosystem, and use [`rehype-sanitize`][sanitize] to make the tree safe. | ||
| As markdown can be turned into HTML and improper use of HTML can open you up to | ||
| [cross-site scripting (XSS)][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`][rehype-sanitize]. | ||
@@ -103,2 +301,4 @@ Use of remark plugins could also open you up to other attacks. | ||
| For info on how to submit a report, see our [security policy][security]. | ||
| ## Contribute | ||
@@ -109,7 +309,4 @@ | ||
| See [`support.md`][support] for ways to get help. | ||
| Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas]. | ||
| Join us in [Discussions][chat] to chat with the community and contributors. | ||
| A curated list of awesome remark resources can be found in [**awesome | ||
| remark**][awesome]. | ||
| This project has a [code of conduct][coc]. | ||
@@ -127,11 +324,19 @@ By interacting with this repository, organization, or community you agree to | ||
| <tr valign="middle"> | ||
| <td width="20%" align="center" colspan="2"> | ||
| <a href="https://www.gatsbyjs.org">Gatsby</a> 🥇<br><br> | ||
| <td width="20%" align="center" rowspan="2" colspan="2"> | ||
| <a href="https://vercel.com">Vercel</a><br><br> | ||
| <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a> | ||
| </td> | ||
| <td width="20%" align="center" rowspan="2" colspan="2"> | ||
| <a href="https://motif.land">Motif</a><br><br> | ||
| <a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a> | ||
| </td> | ||
| <td width="20%" align="center" rowspan="2" colspan="2"> | ||
| <a href="https://www.hashicorp.com">HashiCorp</a><br><br> | ||
| <a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a> | ||
| </td> | ||
| <td width="20%" align="center" rowspan="2" colspan="2"> | ||
| <a href="https://www.gatsbyjs.org">Gatsby</a><br><br> | ||
| <a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a> | ||
| </td> | ||
| <td width="20%" align="center" colspan="2"> | ||
| <a href="https://vercel.com">Vercel</a> 🥇<br><br> | ||
| <a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a> | ||
| </td> | ||
| <td width="20%" align="center" colspan="2"> | ||
| <td width="20%" align="center" rowspan="2" colspan="2"> | ||
| <a href="https://www.netlify.com">Netlify</a><br><br> | ||
@@ -141,5 +346,9 @@ <!--OC has a sharper image--> | ||
| </td> | ||
| </tr> | ||
| <tr valign="middle"> | ||
| </tr> | ||
| <tr valign="middle"> | ||
| <td width="10%" align="center"> | ||
| <a href="https://www.holloway.com">Holloway</a><br><br> | ||
| <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a> | ||
| <a href="https://www.coinbase.com">Coinbase</a><br><br> | ||
| <a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a> | ||
| </td> | ||
@@ -151,2 +360,6 @@ <td width="10%" align="center"> | ||
| <td width="10%" align="center"> | ||
| <a href="https://expo.io">Expo</a><br><br> | ||
| <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a> | ||
| </td> | ||
| <td width="10%" align="center"> | ||
| <a href="https://boosthub.io">Boost Hub</a><br><br> | ||
@@ -156,5 +369,10 @@ <a href="https://boosthub.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a> | ||
| <td width="10%" align="center"> | ||
| <a href="https://expo.io">Expo</a><br><br> | ||
| <a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a> | ||
| <a href="https://www.holloway.com">Holloway</a><br><br> | ||
| <a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a> | ||
| </td> | ||
| <td width="10%"></td> | ||
| <td width="10%"></td> | ||
| <td width="10%"></td> | ||
| <td width="10%"></td> | ||
| <td width="10%"></td> | ||
| </tr> | ||
@@ -198,14 +416,12 @@ <tr valign="middle"> | ||
| [security]: https://github.com/remarkjs/.github/blob/main/security.md | ||
| [health]: https://github.com/remarkjs/.github | ||
| [contributing]: https://github.com/remarkjs/.github/blob/HEAD/contributing.md | ||
| [contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md | ||
| [support]: https://github.com/remarkjs/.github/blob/HEAD/support.md | ||
| [support]: https://github.com/remarkjs/.github/blob/main/support.md | ||
| [coc]: https://github.com/remarkjs/.github/blob/HEAD/code-of-conduct.md | ||
| [coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md | ||
| [ideas]: https://github.com/remarkjs/ideas | ||
| [awesome]: https://github.com/remarkjs/awesome-remark | ||
| [license]: https://github.com/remarkjs/remark/blob/main/license | ||
@@ -217,18 +433,22 @@ | ||
| [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting | ||
| [rehype]: https://github.com/rehypejs/rehype | ||
| [rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize | ||
| [remark]: https://github.com/remarkjs/remark | ||
| [plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md | ||
| [markdown-extensions]: https://github.com/sindresorhus/markdown-extensions | ||
| [config-file]: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/configure.md | ||
| [config-file]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md | ||
| [ignore-file]: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md | ||
| [ignore-file]: https://github.com/unifiedjs/unified-engine/blob/main/doc/ignore.md | ||
| [unified-args]: https://github.com/unifiedjs/unified-args#cli | ||
| [xss]: https://en.wikipedia.org/wiki/Cross-site_scripting | ||
| [remark-core]: ../remark | ||
| [rehype]: https://github.com/rehypejs/rehype | ||
| [remark-toc]: https://github.com/remarkjs/remark-toc | ||
| [sanitize]: https://github.com/rehypejs/rehype-sanitize | ||
| [markdown-style-guide]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by65.06%
18064
- Number of lines in readme file
- increased by98.65%
443
Worsened metrics
- Lines of code
- decreased by-5.88%
32
No dependency changes