Retext

natural language processor powered by plugins part of the @unifiedjs collec...

Text processing
retextjs/retextunifiedjs.comretext

README

[![retext][logo]][unified]

[![Build][build-badge]][build] [![Coverage][coverage-badge]][coverage] [![Downloads][downloads-badge]][downloads] [![Size][size-badge]][size] [![Sponsors][sponsors-badge]][collective] [![Backers][backers-badge]][collective] [![Chat][chat-badge]][chat]

retext is a tool that transforms natural language with plugins.
These plugins can inspect and change the natural language.
You can use retext on the server, the client, deno, etc.

Intro


retext is an ecosystem of plugins that work with natural language as structured
data, specifically ASTs (abstract syntax trees).
ASTs make it easy for programs to deal with prose.
We call those programs plugins.
Plugins inspect and change trees.
You can use the many existing plugins or you can make your own.
Some example use cases are to [check spelling][retext-spell],
[fix typography][retext-smartypants], or
[make sure text is readable][retext-readability].

  for more about us, see [unifiedjs.com][site]
  for updates, see [Twitter][]
  for questions, see [support][]
  to help, see [contribute][] or [sponsor][] below

Contents


  What is this?
  When should I use this?
  Plugins
  Types
  Compatibility
  Contribute
  Sponsor
  License

What is this?


You can use plugins to fix typography.
In:

  1. ```text
  2. He said, "A 'simple' english sentence. . .
  3. ```

Out:

  1. ```text
  2. He said, “A ‘simple’ english sentence…”
  3. ```

You can use plugins to check natural language.
In:

  1. ```text
  2. He’s pretty set on beating your butt for sheriff.
  3. ```

Out:

  1. ```text
  2. example.txt
  3.   1:1-1:5    warning  `He’s` may be insensitive, use `They`, `It` instead  he-she  retext-equality
  4.   1:33-1:37  warning  Be careful with “butt”, it’s profane in some cases  butt  retext-profanities

  6. ⚠ 1 warning
  7. ```

And you can make your own plugins.
You can use retext for many different things.
[unified][] is the core project that transforms content with ASTs.
retext adds support for natural language to unified.
[nlcst][] is the natural language AST that retext uses.

This GitHub repository is a monorepo that contains the following packages:

  [retext-english][retext-english]
    — parse English prose to a syntax tree
  [retext-dutch][retext-dutch]
    — parse Dutch prose to a syntax tree
  [retext-latin][retext-latin]
    — parse any Latin-script prose to a syntax tree
  [retext-stringify][retext-stringify]
    — serialize a syntax tree
  [retext][api]
    — programmatic interface with both retext-latin and retext-stringify

When should I use this?


It is recommended to use unified with retext-english (or retext-dutch)
and retext-stringify if your content is in English (or Dutch).
Otherwise, if your content is in another Latin-script language, use retext.

Plugins


retext plugins deal with natural language.
You can choose from the many plugins that already exist.
Here are three good ways to find plugins:

  [awesome-retext][awesome-retext]
    — selection of the most awesome projects
  [List of plugins][list-of-plugins]
    — list of all plugins
  [retext-plugin topic][topic]
    — any tagged repo on GitHub

Some plugins are maintained by us here in the @retextjs organization while
others are maintained by folks elsewhere.
Anyone can make retext plugins, so as always when choosing whether to include
dependencies in your project, make sure to carefully assess the quality of
retext plugins too.

Types


The retext organization and the unified collective as a whole is fully typed
with [TypeScript][].
Types for nlcst are available in [@types/nlcst][types-nlcst].

For TypeScript to work, it is particularly important to type your plugins
correctly.
We strongly recommend using the Plugin type from unified with its generics
and to use the node types for the syntax trees provided by @types/nlcst.

  1. ```js
  2. /**
  3. * @typedef {import('nlcst').Root} Root
  4. *
  5. * @typedef Options
  6. *   Configuration (optional).
  7. * @property {boolean} [someField]
  8. *   Some option.
  9. */

  11. // To type options and that the it works with `nlcst`:
  12. /** @type {import('unified').Plugin<[Options?], Root>} */
  13. export function myRetextPluginAcceptingOptions(options) {
  14.   // `options` is `Options?`.
  15.   return function (tree, file) {
  16.     // `tree` is `Root`.
  17.   }
  18. }
  19. ```

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+, 16.0+, and 18.0+.
Our projects sometimes work with older versions, but this is not guaranteed.

Contribute


See [contributing.md][contributing] in [retextjs/.github][health] for ways
to get started.
See [support.md][support] for ways to get help.

This project has a [code of conduct][coc].
By interacting with this repository, organization, or community you agree to
abide by its terms.

For info on how to submit a security report, see our
[security policy][security].

Sponsor


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

Vercel

 Motif

 HashiCorp

 GitBook

 Gatsby

Netlify

 Coinbase

 ThemeIsle

 Expo

 Boost Note

 Holloway


You?


License


[MIT][license] © [Titus Wormer][author]


[logo]: https://raw.githubusercontent.com/retextjs/retext/3420f05/logo.svg?sanitize=true

[build-badge]: https://github.com/retextjs/retext/workflows/main/badge.svg

[build]: https://github.com/retextjs/retext/actions

[coverage-badge]: https://img.shields.io/codecov/c/github/retextjs/retext.svg

[coverage]: https://codecov.io/github/retextjs/retext

[downloads-badge]: https://img.shields.io/npm/dm/retext.svg

[downloads]: https://www.npmjs.com/package/retext

[size-badge]: https://img.shields.io/bundlephobia/minzip/retext.svg

[size]: https://bundlephobia.com/result?p=retext

[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg

[backers-badge]: https://opencollective.com/unified/backers/badge.svg

[collective]: https://opencollective.com/unified

[chat]: https://github.com/retextjs/retext/discussions

[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg

[health]: https://github.com/retextjs/.github

[security]: https://github.com/retextjs/.github/blob/main/security.md

[contributing]: https://github.com/retextjs/.github/blob/main/contributing.md

[support]: https://github.com/retextjs/.github/blob/main/support.md

[coc]: https://github.com/retextjs/.github/blob/main/code-of-conduct.md

[license]: license

[author]: https://wooorm.com

[unified]: https://github.com/unifiedjs/unified

[types-nlcst]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/nlcst

[typescript]: https://www.typescriptlang.org

[twitter]: https://twitter.com/unifiedjs

[site]: https://unifiedjs.com

[topic]: https://github.com/topics/retext-plugin

[nlcst]: https://github.com/syntax-tree/nlcst

[awesome-retext]: https://github.com/retextjs/awesome-retext

[retext-english]: https://github.com/retextjs/retext/tree/main/packages/retext-english

[retext-dutch]: https://github.com/retextjs/retext/tree/main/packages/retext-dutch

[retext-latin]: https://github.com/retextjs/retext/tree/main/packages/retext-latin

[retext-stringify]: https://github.com/retextjs/retext/tree/main/packages/retext-stringify

[api]: https://github.com/retextjs/retext/tree/main/packages/retext

[list-of-plugins]: https://github.com/retextjs/retext/tree/main/doc/plugins.md

[retext-spell]: https://github.com/retextjs/retext-spell

[retext-smartypants]: https://github.com/retextjs/retext-smartypants

[retext-readability]: https://github.com/retextjs/retext-readability

[contribute]: #contribute

[sponsor]: #sponsor