Skip to content

Commit 6a43da8

Browse files
wooormwooorm
committed
Refactor docs
1 parent c348aec commit 6a43da8

File tree

9 files changed

+632
-533
lines changed

9 files changed

+632
-533
lines changed

‎packages/remark-cli/readme.md‎

Lines changed: 54 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,9 @@ Command line interface to inspect and change markdown files with **[remark][]**.
2929

3030
This package is a command line interface (CLI) that you can use in your terminal
3131
or in npm scripts and the like to inspect and change markdown files.
32-
This CLI is built around remark, which is a very popular ecosystem of plugins
33-
that work with markdown as structured data, specifically ASTs (abstract syntax
34-
trees).
35-
You can choose from the 150+ plugins that already exist or make your own.
32+
This CLI is built around remark, which is an ecosystem of plugins that work with
33+
markdown as structured data, specifically ASTs (abstract syntax trees).
34+
You can choose from the 150+ existing plugins or make your own.
3635

3736
See [the monorepo readme][remark] for info on what the remark ecosystem is.
3837

@@ -46,8 +45,8 @@ If not, you can always use [`remark`][remark-core] itself manually in a script.
4645

4746
## Install
4847

49-
This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
50-
In Node.js (version 14.14+, or 16.0+), install with [npm][]:
48+
This package is [ESM only][esm].
49+
In Node.js (version 16+), install with [npm][]:
5150

5251
```sh
5352
npm install remark-cli
@@ -58,7 +57,7 @@ npm install remark-cli
5857
Add a table of contents with [`remark-toc`][remark-toc] to `readme.md`:
5958

6059
```sh
61-
remark readme.md --use remark-toc --output
60+
remark readme.md --output --use remark-toc
6261
```
6362

6463
Lint all markdown files in the current directory according to the markdown style
@@ -80,31 +79,32 @@ Usage: remark [options] [path | glob ...]
8079
8180
Options:
8281
82+
--[no-]color specify color in report (on by default)
83+
--[no-]config search for configuration files (on by default)
84+
-e --ext <extensions> specify extensions
85+
--file-path <path> specify path to process as
86+
-f --frail exit with 1 on warnings
8387
-h --help output usage information
84-
-v --version output version number
88+
--[no-]ignore search for ignore files (on by default)
89+
-i --ignore-path <path> specify ignore file
90+
--ignore-path-resolve-from cwd|dir resolve patterns in `ignore-path` from its directory or cwd
91+
--ignore-pattern <globs> specify ignore patterns
92+
--inspect output formatted syntax tree
8593
-o --output [path] specify output location
94+
-q --quiet output only warnings and errors
8695
-r --rc-path <path> specify configuration file
87-
-i --ignore-path <path> specify ignore file
96+
--report <reporter> specify reporter
8897
-s --setting <settings> specify settings
89-
-e --ext <extensions> specify extensions
90-
-u --use <plugins> use plugins
91-
-w --watch watch for changes and reprocess
92-
-q --quiet output only warnings and errors
9398
-S --silent output only errors
94-
-f --frail exit with 1 on warnings
95-
-t --tree specify input and output as syntax tree
96-
--report <reporter> specify reporter
97-
--file-path <path> specify path to process as
98-
--ignore-path-resolve-from dir|cwd resolve patterns in `ignore-path` from its directory or cwd
99-
--ignore-pattern <globs> specify ignore patterns
10099
--silently-ignore do not fail when given ignored files
100+
--[no-]stdout specify writing to stdout (on by default)
101+
-t --tree specify input and output as syntax tree
101102
--tree-in specify input as syntax tree
102103
--tree-out output syntax tree
103-
--inspect output formatted syntax tree
104-
--[no-]stdout specify writing to stdout (on by default)
105-
--[no-]color specify color in report (on by default)
106-
--[no-]config search for configuration files (on by default)
107-
--[no-]ignore search for ignore files (on by default)
104+
-u --use <plugins> use plugins
105+
--verbose report extra info for messages
106+
-v --version output version number
107+
-w --watch watch for changes and reprocess
108108
109109
Examples:
110110
@@ -118,17 +118,17 @@ Examples:
118118
$ remark . -o
119119
```
120120

121-
More information on all these options is available at
122-
[`unified-args`][unified-args], which does the work.
121+
More info on all these options is available at [`unified-args`][unified-args],
122+
which does the work.
123123
`remark-cli` is `unified-args` preconfigured to:
124124

125-
* Load `remark-` plugins
126-
* Search for markdown extensions
125+
* load `remark-` plugins
126+
* search for markdown extensions
127127
([`.md`, `.markdown`, etc][markdown-extensions])
128-
* Ignore paths found in [`.remarkignore` files][ignore-file]
129-
* Load configuration from
128+
* ignore paths found in [`.remarkignore` files][ignore-file]
129+
* load configuration from
130130
[`.remarkrc`, `.remarkrc.js`, etc files][config-file]
131-
* Use configuration from
131+
* use configuration from
132132
[`remarkConfig` fields in `package.json` files][config-file]
133133

134134
## Examples
@@ -138,13 +138,13 @@ More information on all these options is available at
138138
This example checks and formats markdown with `remark-cli`.
139139
It assumes you’re in a Node.js package.
140140

141-
First, install the CLI and plugins:
141+
Install the CLI and plugins:
142142

143143
```sh
144-
npm install remark-cli remark-toc remark-preset-lint-consistent remark-preset-lint-recommended --save-dev
144+
npm install remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc --save-dev
145145
```
146146

147-
Now, add an npm script in your `package.json`:
147+
…then add an npm script in your `package.json`:
148148

149149
```js
150150
/* … */
@@ -158,7 +158,7 @@ Now, add an npm script in your `package.json`:
158158

159159
> 💡 **Tip**: add ESLint and such in the `format` script too.
160160
161-
Observe that the above change adds a `format` script, which can be run with
161+
The above change adds a `format` script, which can be run with
162162
`npm run format`.
163163
It runs remark on all markdown files (`.`) and rewrites them (`--output`).
164164
Run `./node_modules/.bin/remark --help` for more info on the CLI.
@@ -188,7 +188,7 @@ Then, add a `remarkConfig` to your `package.json` to configure remark:
188188
```
189189

190190
> 👉 **Note**: you must remove the comments in the above examples when
191-
> copy/pasting them, as comments are not supported in `package.json` files.
191+
> copy/pasting them as comments are not supported in `package.json` files.
192192
193193
Finally, you can run the npm script to check and format markdown files in your
194194
project:
@@ -269,20 +269,23 @@ Earlier wins (so in the above file structure `folder/.remarkrc.js` wins over
269269
`folder/package.json`):
270270

271271
1. `.remarkrc` (JSON)
272-
2. `.remarkrc.json` (JSON)
273272
3. `.remarkrc.cjs` (CJS)
274-
4. `.remarkrc.mjs` (ESM)
275273
5. `.remarkrc.js` (CJS or ESM, depending on `type: 'module'` in `package.json`)
274+
2. `.remarkrc.json` (JSON)
275+
4. `.remarkrc.mjs` (ESM)
276276
6. `.remarkrc.yaml` (YAML)
277277
7. `.remarkrc.yml` (YAML)
278278
8. `package.json` with `remarkConfig` field
279279

280280
## Compatibility
281281

282-
Projects maintained by the unified collective are compatible with all maintained
282+
Projects maintained by the unified collective are compatible with maintained
283283
versions of Node.js.
284-
As of now, that is Node.js 14.14+, and 16.0+.
285-
Our projects sometimes work with older versions, but this is not guaranteed.
284+
285+
When we cut a new major release, we drop support for unmaintained versions of
286+
Node.
287+
This means we try to keep the current release line, `remark-cli@^11`,
288+
compatible with Node.js 12.
286289

287290
## Security
288291

@@ -311,8 +314,6 @@ abide by its terms.
311314

312315
Support this effort and give back by sponsoring on [OpenCollective][collective]!
313316

314-
<!--lint ignore no-html-->
315-
316317
<table>
317318
<tr valign="middle">
318319
<td width="20%" align="center" rowspan="2" colspan="2">
@@ -424,24 +425,26 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!
424425

425426
[npm]: https://docs.npmjs.com/cli/install
426427

427-
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
428+
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
429+
430+
[markdown-extensions]: https://github.com/sindresorhus/markdown-extensions
428431

429432
[rehype]: https://github.com/rehypejs/rehype
430433

431434
[rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
432435

433436
[remark]: https://github.com/remarkjs/remark
434437

435-
[markdown-extensions]: https://github.com/sindresorhus/markdown-extensions
436-
437-
[config-file]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md
438+
[remark-core]: ../remark/
438439

439-
[ignore-file]: https://github.com/unifiedjs/unified-engine/blob/main/doc/ignore.md
440+
[remark-toc]: https://github.com/remarkjs/remark-toc
440441

441-
[unified-args]: https://github.com/unifiedjs/unified-args#cli
442+
[config-file]: https://github.com/unifiedjs/unified-engine#config-files
442443

443-
[remark-core]: ../remark
444+
[ignore-file]: https://github.com/unifiedjs/unified-engine#ignore-files
444445

445-
[remark-toc]: https://github.com/remarkjs/remark-toc
446+
[unified-args]: https://github.com/unifiedjs/unified-args#cli
446447

447448
[markdown-style-guide]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide
449+
450+
[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting

‎packages/remark-parse/index.d.ts‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import type {Root} from 'mdast'
2-
import type {Extension} from 'mdast-util-from-markdown'
2+
import type {Extension as FromMarkdownExtension} from 'mdast-util-from-markdown'
33
import type {Extension as MicromarkExtension} from 'micromark-util-types'
44
import type {Plugin} from 'unified'
55
import type {Options} from './lib/index.js'
@@ -28,7 +28,28 @@ declare module 'unified' {
2828
interface Settings extends Options {}
2929

3030
interface Data {
31+
/**
32+
* List of `micromark` extensions to use.
33+
*
34+
* This type is registered by `remark-parse`.
35+
* Values can be registered by remark plugins that extend `micromark` and
36+
* `mdast-util-from-markdown`.
37+
* See {@link MicromarkExtension | `Extension`} from
38+
* {@link https://github.com/micromark/micromark/tree/main/packages/micromark-util-types | `micromark-util-types`}.
39+
*/
3140
micromarkExtensions?: MicromarkExtension[]
32-
fromMarkdownExtensions?: Array<Extension[] | Extension>
41+
42+
/**
43+
* List of `mdast-util-from-markdown` extensions to use.
44+
*
45+
* This type is registered by `remark-parse`.
46+
* Values can be registered by remark plugins that extend `micromark` and
47+
* `mdast-util-from-markdown`.
48+
* See {@link FromMarkdownExtension | `Extension`} from
49+
* {@link https://github.com/syntax-tree/mdast-util-from-markdown#extension | `mdast-util-from-markdown`}.
50+
*/
51+
fromMarkdownExtensions?: Array<
52+
FromMarkdownExtension[] | FromMarkdownExtension
53+
>
3354
}
3455
}

‎packages/remark-parse/lib/index.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
*/
77

88
/**
9-
* @typedef {Omit<FromMarkdownOptions, 'extensions' | 'fromMarkdownExtensions'>} Options
9+
* @typedef {Omit<FromMarkdownOptions, 'extensions' | 'mdastExtensions'>} Options
1010
*/
1111

1212
import {fromMarkdown} from 'mdast-util-from-markdown'

0 commit comments

Comments
 (0)