Skip to content

Commit

Permalink
Refactor docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@wooorm
wooorm committed Aug 24, 2023
1 parent 432090a commit 570f806
Show file tree
Hide file tree
Showing 2 changed files with 68 additions and 183 deletions.
8 changes: 7 additions & 1 deletion lib/index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,12 @@
* @typedef {Transform & FileStreamFields} FileStream
* File stream.
*
* Streaming vinyl files are not supported.
*
* There’s also a `fileStream.use()` function, which is like `unified.use()`,
* in that it accepts a plugin and configuration or a preset.
* It returns the operated on `fileStream`.
*
* @typedef FileStreamFields
* Extra file stream fields.
* @property {Use} use
Expand Down Expand Up @@ -63,7 +69,7 @@ import {engine} from 'unified-engine'
* @param {Options} options
* Configuration.
* @returns
* Gulp Plugin.
* Gulp plugin.
*/
export function gulpEngine(options) {
if (!options || !options.name) {
Expand Down
243 changes: 61 additions & 182 deletions readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ processor.
* [Use](#use)
* [API](#api)
* [`engineGulp(options)`](#enginegulpoptions)
* [`FileStream`](#filestream)
* [`Options`](#options)
* [Debugging](#debugging)
* [Types](#types)
* [Compatibility](#compatibility)
Expand All @@ -39,7 +41,7 @@ configure from the file system.
## Install

This package is [ESM only][esm].
In Node.js (version 14.14+, 16.0+, or 18.0+), install with [npm][]:
In Node.js (version 16+), install with [npm][]:

```sh
npm install unified-engine-gulp
Expand All @@ -48,12 +50,12 @@ npm install unified-engine-gulp
## Use

```js
import {engineGulp} from 'unified-engine-gulp'
import {remark} from 'remark'
import {engineGulp} from 'unified-engine-gulp'

export const gulpRemark = engineGulp({
name: 'gulp-remark',
ignoreName: '.remarkignore',
name: 'gulp-remark',
packageField: 'remarkConfig',
pluginPrefix: 'remark',
processor: remark,
Expand All @@ -63,148 +65,71 @@ export const gulpRemark = engineGulp({

## API

This package exports the identifier `engineGulp`.
This package exports the identifier [`engineGulp`][api-engine-gulp].
There is no default export.

### `engineGulp(options)`

Create a [Gulp][] plugin from a unified processor.
Create a [Gulp][] plugin.

> 👉 **Note**: see [writing a Gulp plugin][plugin] for more info.
##### `options`

Anything not passed in `options`, but in the below list, can be set later by
users of the plugin.

###### `options.name` (`string`, required)

Name of Gulp plugin (used in errors).

###### [`options.processor`][processor]

Processor to inspect and transform files ([`Processor`][unified-processor],
required).

###### [`options.streamError`][stream-error]

Stream to write the report (if any) to (`WritableStream`, default:
`process.stderr`).

###### [`options.tree`][tree]

Whether to treat both input and output as a syntax tree (`boolean`, default:
`false`).

###### [`options.treeIn`][tree-in]

Whether to treat input as a syntax tree (`boolean`, default: `tree`).

###### [`options.treeOut`][tree-out]

Whether to treat output as a syntax tree (`boolean`, default: `tree`).

###### [`options.inspect`][inspect]

Skip the compilation phase and output a syntax tree formatted with
[`unist-util-inspect`][unist-util-inspect] (`boolean`, default: `false`).

###### [`options.rcName`][rc-name]

Name of configuration files to load (`string`, optional).

###### [`options.packageField`][package-field]

Field at which configuration can be found in `package.json`
files (`string`, optional).

###### [`options.detectConfig`][detect-config]

Whether to search for configuration files (`boolean`, default: whether
`rcName` or `packageField` is given).

###### [`options.rcPath`][rc-path]

File-path to a configuration file to load (`string`, optional).

###### [`options.settings`][settings]

Configuration for the parser and compiler of the processor (`Object`, optional).

###### [`options.ignoreName`][ignore-name]

Name of ignore files to load (`string`, optional).

###### [`options.detectIgnore`][detect-ignore]

Whether to search for ignore files (`boolean`, default: whether `ignoreName`
is given).

###### [`options.ignorePath`][ignore-path]

File-path to an ignore file to load (`string`, optional).

###### [`options.ignorePathResolveFrom`][ignore-path-resolve-from]

Whether to resolve patterns in `ignorePath` relative to its directory or the
current working directory (`'dir'` or `'cwd'`, default: `'dir'`).

###### [`options.ignorePatterns`][ignore-patterns]

Extra patterns to ignore in combination with `ignorePath` or found ignores
(`Array<string>`, optional).

###### [`options.plugins`][plugins]

Map of plug-in names or paths and options to use (`Object`, optional).

###### [`options.pluginPrefix`][plugin-prefix]

When given, optional prefix to use when searching for plug-ins (`string`,
optional).

###### [`options.defaultConfig`][default-config]
###### Parameters

Optional object with plugins and/or settings to use if no config file is
supplied by the user (`Object`, optional).
* `options` ([`Options`][api-options], required])
— configuration

###### [`options.configTransform`][config-transform]
###### Returns

Transform config files from a different schema (`Function`, optional).
Gulp plugin, which can be called with options (same as [`Options`][api-options]
but w/o `name` or `processor`) and returns a [`through2`][through2] stream
accepting Vinyl files ([`FileStream`][api-file-stream]).

###### [`options.reporter`][reporter]
### `FileStream`

Reporter to use (`string` or `function`, default: `require('vfile-reporter')`).
File stream (TypeScript type).

###### [`options.reporterOptions`][reporteroptions]

Config to pass to the used reporter (`Object?`, optional).

###### [`options.color`][color]
Streaming vinyl files are not supported.
Read more about why in [Gulp’s docs (point 10)][streaming].

Whether to report with ANSI color sequences (`boolean`, default: `false`).
There’s also a `fileStream.use()` function, which is like
[`unified.use()`][use], in that it accepts a plugin and configuration or a
preset.
It returns the operated on `fileStream`.

###### [`options.silent`][silent]
###### Type

Report only fatal errors (`boolean`, default: `false`).
```ts
import type {Transform} from 'node:stream'

###### [`options.quiet`][quiet]
type FileStream = Transform & {use: Use}

Do not report successful files (`boolean`, default: `silent`).
type Use = (...values: unknown[]) => FileStream
```
###### [`options.frail`][frail]
### `Options`
Treat warnings as errors (`boolean`, default: `false`).
Configuration (TypeScript type).
##### Returns
###### Type
An [`through2`][through2] object stream, accepting Vinyl files (`fileStream`).
Streaming vinyl files are not supported.
Read more about why in [Gulp’s docs (point 10)][streaming].
```ts
import type {EngineOptions} from 'unified-engine'

There’s also a `fileStream.use()` function, which is like
[`unified.use()`][use], in that it accepts a plugin and configuration.
It returns the operated on `fileStream`.
type Options = {name: string} & Omit<
EngineOptions,
| 'alwaysStringify'
| 'cwd'
| 'extensions'
| 'files'
| 'out'
| 'output'
| 'plugins'
| 'silentlyIgnore'
| 'streamIn'
| 'streamOut'
>
```
## Debugging
Expand All @@ -214,14 +139,18 @@ to `*`, such as `DEBUG="*" gulp …`.
## Types
This package is fully typed with [TypeScript][].
It export the additional types `FileStream` and `Options`.
It exports the additional types [`FileStream`][api-file-stream] and
[`Options`][api-options].
## 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+, 16.0+, and 18.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, `unified-engine-gulp@^10`,
compatible with Node.js 12.
## Security
Expand Down Expand Up @@ -289,64 +218,10 @@ abide by its terms.
[unified]: https://github.com/unifiedjs/unified
[unified-processor]: https://github.com/unifiedjs/unified#processor

[use]: https://github.com/unifiedjs/unified#processoruseplugin-options
[processor]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsprocessor

[unified-engine]: https://github.com/unifiedjs/unified-engine
[detect-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsdetectconfig

[stream-error]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsstreamerror

[tree]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionstree

[tree-in]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionstreein

[tree-out]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionstreeout

[inspect]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsinspect

[rc-name]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsrcname

[package-field]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionspackagefield

[rc-path]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsrcpath

[settings]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionssettings

[detect-ignore]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsdetectignore

[ignore-name]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsignorename

[ignore-path]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsignorepath

[ignore-path-resolve-from]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsignorepathresolvefrom

[ignore-patterns]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsignorepatterns

[plugin-prefix]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionspluginprefix

[default-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsdefaultconfig

[config-transform]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsconfigtransform

[plugins]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsplugins

[reporter]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsreporter

[reporteroptions]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsreporteroptions

[color]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionscolor

[silent]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionssilent

[quiet]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsquiet

[frail]: https://github.com/unifiedjs/unified-engine/blob/main/doc/options.md#optionsfrail

[debug]: https://github.com/debug-js/debug
[gulp]: https://gulpjs.com
Expand All @@ -357,6 +232,10 @@ abide by its terms.
[through2]: https://github.com/rvagg/through2#readme
[unist-util-inspect]: https://github.com/syntax-tree/unist-util-inspect

[gulp-remark]: https://github.com/remarkjs/gulp-remark
[api-engine-gulp]: #enginegulpoptions
[api-file-stream]: #filestream
[api-options]: #options

0 comments on commit 570f806

Please sign in to comment.