Add improved docs

packages/remark-cli/readme.md

@@ -7,39 +7,70 @@
 [![Backers][backers-badge]][collective]
 [![Chat][chat-badge]][chat]
 
-Command line interface for [**remark**][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]
+Command line interface to inspect and change markdown files with **[remark][]**.
+
+## 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)
+* [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: ASTs (short for 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][]:
 
 ```sh
 npm install remark-cli
 ```
 
 ## Use
 
+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 all markdown files in the current directory according to the markdown style
+guide with [`remark-preset-lint-markdown-style-guide`][markdown-style-guide].
 
-# Lint markdown files in the current directory
-# according to the markdown style guide.
-$ remark . --use preset-lint-markdown-style-guide
+```sh
+remark . --use remark-preset-lint-markdown-style-guide
 ```
 
 ## CLI
 
-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`):
 
 ```txt
 Usage: remark [options] [path | glob ...]
@@ -86,12 +117,90 @@ Examples:
  $ remark . -o
 ```
 
+More information on all these options is available in detail at
+[`unified-args`][unified-args], which does most of 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
+
+The following example checks and formats markdown with `remark-cli`.
+
+This example 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",
+ /* … */
+ },
+ /* … */
+```
+
+Observe that the above change adds a `format` script, which can be run with
+`npm run format` (tip: add eslint and such there as well).
+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.
+ "remark-toc" // Generate a table of contents in `## Table of contents`
+ ]
+ },
+ /* … */
+```
+
+Note that you must remove the comments in the above examples when copy/pasting
+them, as comments are not supported in a `package.json` file.
+
+Finally, you can run the npm script to check and format the markdown in your
+project:
+
+```sh
+npm run format
+```
+
+## 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].
 
 Use of remark plugins could also open you up to other attacks.
 Carefully assess each plugin and the risks involved in using them.
@@ -101,10 +210,7 @@ Carefully assess each plugin and the risks involved in using them.
 See [`contributing.md`][contributing] in [`remarkjs/.github`][health] for ways
 to get started.
 See [`support.md`][support] for ways to get help.
-Ideas for new plugins and tools can be posted in [`remarkjs/ideas`][ideas].
-
-A curated list of awesome remark resources can be found in [**awesome
-remark**][awesome].
+Join us in [Discussions][chat] to chat with the community and contributors.
 
 This project has a [code of conduct][coc].
 By interacting with this repository, organization, or community you agree to
@@ -118,35 +224,56 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
 <table>
 <tr valign="middle">
-<td width="20%" align="center" 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>
+<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" colspan="2">
+<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" rowspan="2" colspan="2">
  <a href="https://www.netlify.com">Netlify</a><br><br>
  <!--OC has a sharper image-->
  <a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
 </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>
 <td width="10%" align="center">
  <a href="https://themeisle.com">ThemeIsle</a><br><br>
  <a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
 </td>
+<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>
  <a href="https://boosthub.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
 </td>
 <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>
 <tr valign="middle">
 <td width="100%" align="center" colspan="10">
@@ -193,19 +320,19 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
 [coc]: https://github.com/remarkjs/.github/blob/HEAD/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
 
 [author]: https://wooorm.com
 
 [npm]: https://docs.npmjs.com/cli/install
 
-[remark]: https://github.com/remarkjs/remark
+[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
+
+[rehype]: https://github.com/rehypejs/rehype
 
-[plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md
+[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
+
+[remark]: https://github.com/remarkjs/remark
 
 [markdown-extensions]: https://github.com/sindresorhus/markdown-extensions
 
@@ -215,8 +342,8 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!
 
 [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