Skip to content

Commit

Permalink
Refactor docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Sep 13, 2023
1 parent c348aec commit 6a43da8
Show file tree
Hide file tree
Showing 9 changed files with 632 additions and 533 deletions.
105 changes: 54 additions & 51 deletions packages/remark-cli/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,10 +29,9 @@ Command line interface to inspect and change markdown files with **[remark][]**.

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.
This CLI is built around remark, which is an ecosystem of plugins that work with
markdown as structured data, specifically ASTs (abstract syntax trees).
You can choose from the 150+ existing plugins or make your own.

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

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

## Install

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

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

```sh
remark readme.md --use remark-toc --output
remark readme.md --output --use remark-toc
```

Lint all markdown files in the current directory according to the markdown style
Expand All @@ -80,31 +79,32 @@ Usage: remark [options] [path | glob ...]
Options:
--[no-]color specify color in report (on by default)
--[no-]config search for configuration files (on by default)
-e --ext <extensions> specify extensions
--file-path <path> specify path to process as
-f --frail exit with 1 on warnings
-h --help output usage information
-v --version output version number
--[no-]ignore search for ignore files (on by default)
-i --ignore-path <path> specify ignore file
--ignore-path-resolve-from cwd|dir resolve patterns in `ignore-path` from its directory or cwd
--ignore-pattern <globs> specify ignore patterns
--inspect output formatted syntax tree
-o --output [path] specify output location
-q --quiet output only warnings and errors
-r --rc-path <path> specify configuration file
-i --ignore-path <path> specify ignore file
--report <reporter> specify reporter
-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
--[no-]stdout specify writing to stdout (on by default)
-t --tree specify input and output as syntax tree
--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)
-u --use <plugins> use plugins
--verbose report extra info for messages
-v --version output version number
-w --watch watch for changes and reprocess
Examples:
Expand All @@ -118,17 +118,17 @@ Examples:
$ remark . -o
```

More information on all these options is available at
[`unified-args`][unified-args], which does the work.
More info 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
* load `remark-` plugins
* search for markdown extensions
([`.md`, `.markdown`, etc][markdown-extensions])
* Ignore paths found in [`.remarkignore` files][ignore-file]
* Load configuration from
* ignore paths found in [`.remarkignore` files][ignore-file]
* load configuration from
[`.remarkrc`, `.remarkrc.js`, etc files][config-file]
* Use configuration from
* use configuration from
[`remarkConfig` fields in `package.json` files][config-file]

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

First, install the CLI and plugins:
Install the CLI and plugins:

```sh
npm install remark-cli remark-toc remark-preset-lint-consistent remark-preset-lint-recommended --save-dev
npm install remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc --save-dev
```

Now, add an npm script in your `package.json`:
…then add an npm script in your `package.json`:

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

> 💡 **Tip**: add ESLint and such in the `format` script too.
Observe that the above change adds a `format` script, which can be run with
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.
Expand Down Expand Up @@ -188,7 +188,7 @@ Then, add a `remarkConfig` to your `package.json` to configure remark:
```

> 👉 **Note**: you must remove the comments in the above examples when
> copy/pasting them, as comments are not supported in `package.json` files.
> 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:
Expand Down Expand Up @@ -269,20 +269,23 @@ Earlier wins (so in the above file structure `folder/.remarkrc.js` wins over
`folder/package.json`):

1. `.remarkrc` (JSON)
2. `.remarkrc.json` (JSON)
3. `.remarkrc.cjs` (CJS)
4. `.remarkrc.mjs` (ESM)
5. `.remarkrc.js` (CJS or ESM, depending on `type: 'module'` in `package.json`)
2. `.remarkrc.json` (JSON)
4. `.remarkrc.mjs` (ESM)
6. `.remarkrc.yaml` (YAML)
7. `.remarkrc.yml` (YAML)
8. `package.json` with `remarkConfig` field

## Compatibility

Projects maintained by the unified collective are compatible with all maintained
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
As of now, that is Node.js 14.14+, and 16.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, `remark-cli@^11`,
compatible with Node.js 12.

## Security

Expand Down Expand Up @@ -311,8 +314,6 @@ abide by its terms.

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

<!--lint ignore no-html-->

<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
Expand Down Expand Up @@ -424,24 +425,26 @@ Support this effort and give back by sponsoring on [OpenCollective][collective]!

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

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c

[markdown-extensions]: https://github.com/sindresorhus/markdown-extensions

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

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

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

[markdown-extensions]: https://github.com/sindresorhus/markdown-extensions

[config-file]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md
[remark-core]: ../remark/

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

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

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

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

[markdown-style-guide]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide

[xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
25 changes: 23 additions & 2 deletions packages/remark-parse/index.d.ts
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import type {Root} from 'mdast'
import type {Extension} from 'mdast-util-from-markdown'
import type {Extension as FromMarkdownExtension} from 'mdast-util-from-markdown'
import type {Extension as MicromarkExtension} from 'micromark-util-types'
import type {Plugin} from 'unified'
import type {Options} from './lib/index.js'
Expand Down Expand Up @@ -28,7 +28,28 @@ declare module 'unified' {
interface Settings extends Options {}

interface Data {
/**
* List of `micromark` extensions to use.
*
* This type is registered by `remark-parse`.
* Values can be registered by remark plugins that extend `micromark` and
* `mdast-util-from-markdown`.
* See {@link MicromarkExtension | `Extension`} from
* {@link https://github.com/micromark/micromark/tree/main/packages/micromark-util-types | `micromark-util-types`}.
*/
micromarkExtensions?: MicromarkExtension[]
fromMarkdownExtensions?: Array<Extension[] | Extension>

/**
* List of `mdast-util-from-markdown` extensions to use.
*
* This type is registered by `remark-parse`.
* Values can be registered by remark plugins that extend `micromark` and
* `mdast-util-from-markdown`.
* See {@link FromMarkdownExtension | `Extension`} from
* {@link https://github.com/syntax-tree/mdast-util-from-markdown#extension | `mdast-util-from-markdown`}.
*/
fromMarkdownExtensions?: Array<
FromMarkdownExtension[] | FromMarkdownExtension
>
}
}
2 changes: 1 addition & 1 deletion packages/remark-parse/lib/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
*/

/**
* @typedef {Omit<FromMarkdownOptions, 'extensions' | 'fromMarkdownExtensions'>} Options
* @typedef {Omit<FromMarkdownOptions, 'extensions' | 'mdastExtensions'>} Options
*/

import {fromMarkdown} from 'mdast-util-from-markdown'
Expand Down
Loading

0 comments on commit 6a43da8

Please sign in to comment.