diff --git a/doc/getting-started.md b/doc/getting-started.md index ff13ca4..3ae12fa 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -1,81 +1,6 @@ -![retext][logo] +# Getting started -# Getting Started +See [the monorepo readme][retext] for what the retext ecosystem is and examples +of how to get started. -**retext** transforms natural language. -It’s an ecosystem of [plugins][]. -If you get stuck, [issues][] and [discussions][] are good places to get help. - -retext is built on [unified][], make sure to read it and its [website][] too. - -## Contents - -* [Introduction](#introduction) -* [Programmatic usage](#programmatic-usage) - -## Introduction - -Out of the box, **retext** doesn’t do anything. -But much can be done [through plugins][plugins]. - -## Programmatic usage - -The programmatic interface of **retext** is provided by [**unified**][unified]. -In fact, [`retext`][api] is two plugins: -[`retext-latin`][latin] and [`retext-stringify`][stringify]. - -Install [`retext`][api] with [npm][]: - -```bash -npm install retext retext-equality retext-simplify -``` - -`index.js` contains: - -```js -import {retext} from 'retext' -import {reporter} from 'vfile-reporter' -import retextSimplify from 'retext-simplify' -import retextEquality from 'retext-equality' - -retext() - .use(retextSimplify) - .use(retextEquality) - .process('Hey guys, utilize a shorter word.') - .then((file) => { - console.log(String(file)) - console.error(reporter(file)) - }) -``` - -`node index.js` yields: - -```txt -Hey guys, utilize a shorter word. - 1:5-1:9 warning `guys` may be insensitive, use `people`, `persons`, `folks` instead gals-men retext-equality - 1:11-1:18 warning Replace `utilize` with `use` utilize retext-simplify - -⚠ 2 warnings -``` - - - -[logo]: https://raw.githubusercontent.com/retextjs/retext/3420f05/logo.svg?sanitize=true - -[issues]: https://github.com/retextjs/retext/issues - -[discussions]: https://github.com/retextjs/retext/discussions - -[npm]: https://docs.npmjs.com/cli/install - -[api]: https://github.com/retextjs/retext/tree/main/packages/retext - -[plugins]: https://github.com/retextjs/retext/tree/main/doc/plugins.md - -[unified]: https://github.com/unifiedjs/unified - -[website]: https://unifiedjs.com - -[latin]: https://github.com/retextjs/retext/tree/main/packages/retext-latin - -[stringify]: https://github.com/retextjs/retext/tree/main/packages/retext-stringify +[retext]: https://github.com/retextjs/retext diff --git a/doc/plugins.md b/doc/plugins.md index 1d60b3d..d1f98fc 100644 --- a/doc/plugins.md +++ b/doc/plugins.md @@ -2,8 +2,9 @@ # Plugins -**retext** is a natural language processor powered by plugins part of the -[unified][] [collective][]. +**retext** is a tool that transforms natural language with plugins. +See [the monorepo readme][retext] for info on what the retext ecosystem is. +This page lists existing plugins. ## Contents @@ -14,12 +15,12 @@ ## List of plugins -See [awesome retext][awesome] for the most awesome projects in the ecosystem. +See [`awesome-retext`][awesome-retext] for the most awesome projects in the +ecosystem. More plugins can be found on GitHub tagged with the [`retext-plugin` topic][topic]. -Have a good idea for a new plugin? -See [Creating plugins][create] below. +The list of plugins: * [`retext-assuming`](https://github.com/davidhund/retext-assuming) — check for unhelpful phrases such as `just`, `simply`, `obviously` @@ -80,40 +81,42 @@ See [Creating plugins][create] below. ## List of utilities -See [**nlcst**][nlcst-util] for a list of utilities for working with the syntax -tree. -See [**unist**][unist-util] for other utilities which work with **nlcst** nodes, -too. -Finally, see [**vfile**][vfile-util] for a list of utilities working with -virtual files. +See [nlcst][nlcst-util] for a list of utilities that work with the syntax tree. +See [unist][unist-util] for other utilities which work with nlcst and other +syntax trees too. +Finally, see [vfile][vfile-util] for a list of utilities working with virtual +files. ## Using plugins -To use a plugin invoke the [`use()`][unified-use] function. +To use a plugin programmatically, call the [`use()`][unified-use] function. ## Creating plugins -Have an idea for a plugin? -Post it in [ideas][] and make it happen! - To create a plugin, first read up on the [concept of plugins][unified-plugins]. Then, read the [guide on “Creating a plugin with unified”][guide]. Finally, take one of existing plugins, which looks similar to what you’re about to make, and work from there. -If you get stuck, [ideas][], [discussions][], and [issues][] are good places to -get help. - -You should pick a name prefixed by `'retext-'`, such as `retext-spell`. +If you get stuck, [discussions][] is a good place to get help. +You should pick a name prefixed by `'retext-'` (such as `retext-emoji`). **Do not use the `retext-` prefix** if the thing you create doesn’t work with `retext().use()`: it isn’t a “plugin” and will confuse users. -If it works with nlcst, use `'nlcst-util-'`, if it works with any unist tree, -use `unist-util-`, and if it works with virtual files, use `vfile-`. +If it works with nlcst, use `'nlcst-'`, if it works with any unist tree, use +`unist-util-`, and if it works with virtual files, use `vfile-`. + +Use default exports to expose plugins from your packages, add `retext-plugin` +keywords in `package.json`, add a `retext-plugin` topic to your repo on GitHub, +and create a pull request to add the plugin here on this page! [logo]: https://raw.githubusercontent.com/retextjs/retext/3420f05/logo.svg?sanitize=true +[retext]: https://github.com/retextjs/retext + +[awesome-retext]: https://github.com/retextjs/awesome-retext + [nlcst-util]: https://github.com/syntax-tree/nlcst#list-of-utilities [unist-util]: https://github.com/syntax-tree/unist#unist-node-utilties @@ -124,20 +127,8 @@ use `unist-util-`, and if it works with virtual files, use `vfile-`. [unified-plugins]: https://github.com/unifiedjs/unified#plugin -[issues]: https://github.com/retextjs/retext/issues - [discussions]: https://github.com/retextjs/retext/discussions [guide]: https://unifiedjs.com/learn/guide/create-a-plugin/ -[unified]: https://github.com/unifiedjs/unified - -[collective]: https://opencollective.com/unified - -[create]: #creating-plugins - -[awesome]: https://github.com/retextjs/awesome-retext - -[ideas]: https://github.com/retextjs/ideas - [topic]: https://github.com/topics/retext-plugin